home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / fish / 751-760 / 757 / wbstart / wbstart.doc < prev    next >
Text File  |  1995-03-18  |  5KB  |  120 lines
  1. Documentation for WBStart V1.2                                       21.09.1991
  2.  
  3. This program is freely distributable, but copyrighted by me. This means that
  4. you can copy it freely as long as you don't ask for any more money than a
  5. nominal fee for copying. THIS APPLIES TO GERMAN PD DEALERS TOO!!! This program
  6. may be put on PD disks, especially on Fred Fish's AmigaLibDisks. If you want to
  7. distribute this program you MUST keep this document and the source code with
  8. it. Program, document and source code must be distributed in their original
  9. unmodified form. Of course you can use an archiver like LHarc to make it
  10. available on mailboxes and FTP sites. This program cannot be used for
  11. commercial purposes without written permission from the author. The author can
  12. not be made responsible for any damage which is caused by using this program.
  13.  
  14. Send comments, suggestions or bug reports to:
  15.  
  16.    Snail : Stefan Becker, Holsteinstrasse 9, 5100 Aachen, GERMANY
  17.    Domain: stefanb@cip-s01.informatik.rwth-aachen.de
  18.  
  19.  
  20.    I. What does it do?
  21.  
  22. WBStart is a package to emulate the Workbench startup procedure. Emulating this
  23. method is easy, because you only have to load a program, create a process for
  24. it and then send a WB startup message to it. But this startup message is a
  25. problem, because it contains memory and directory locks owned by your process
  26. and it is only returned after the WB process ends. So you can't leave your
  27. program until ALL WB processes you created have ended, or the replied messages
  28. will go into nowhere land.
  29.  
  30. WBStart solves this problem by using a handler process, which does the starting
  31. of the processes for you and then waits for the reply messages. You just send a
  32. message to the handler port, containing all needed information like name and
  33. parameters. The handler duplicates this information (so you can free your copy
  34. without worry and leave your program) and then starts the process.
  35.  
  36.  
  37.   II. Installation & Usage
  38.  
  39. Just copy the file WBStart-Handler into your L: directory. Be sure to set the
  40. execute flag on this file with
  41.  
  42.    Protect L:WBStart-Handler +e
  43.  
  44. You can break WBStart-Handler by sending a CTRL-C to its process. If all WB
  45. processes have returned, it will exit then.
  46.  
  47. WBStarter is an example program how to use the handler. It has the following
  48. syntax:
  49.  
  50.    WBStarter <command> [<command> ...]
  51.  
  52. WBStarter tries to start every command as WB process without parameters. The
  53. file names must contain absolute paths, or the handler won't be able to find
  54. the executables. If the handler is not running, WBStarter tries to start it.
  55.  
  56.  
  57.  III. How to use WBStart-Handler in your program
  58.  
  59. The handler opens a public message port named "WBStart-Handler Port". You must
  60. send a message of the following type to this port:
  61.  
  62.    struct WBStartMsg {
  63.                       struct Message  wbsm_Msg;
  64.                       char           *wbsm_Name;
  65.                       BPTR            wbsm_DirLock;
  66.                       ULONG           wbsm_Stack;
  67.                       LONG            wbsm_Prio;
  68.                       ULONG           wbsm_NumArgs;
  69.                       struct WBArg   *wbsm_ArgList;
  70.                      };
  71.  
  72.  wbsm_Msg
  73.   Standard message structure. You MUST initialize the mn_ReplyPort field to
  74.   your own message port.
  75.  
  76.  wbsm_Name
  77.   Pointer to a string, which contains the name of the program. The handler
  78.   recognizes project icons and extracts the default tool.
  79.  
  80.  wbsm_DirLock
  81.   Lock on a directory. wbsm_Name will be used relative to this directory.
  82.  
  83.  wbsm_Stack
  84.   Stack size for the new process. Minimum is 4096 Bytes. If a tool icon exists,
  85.   then the stack size from the icon is used. When this message is replied, this
  86.   field contains a boolean, which indicates the success of the action.
  87.  
  88.  wbsm_Prio
  89.   Priority of the new process. Must be in the range -128..127.
  90.  
  91.  wbsm_NumArgs
  92.   Number of arguments in wbsm_ArgList. May be 0.
  93.  
  94.  wbsm_ArgList
  95.   Pointer to an array of WB Arguments. These arguments contain lock on a
  96.   directory  and a pointer to a file name, which is relative to the directory.
  97.   Look into <workbench/startup.h> for the definition of this data structure.
  98.  
  99. Look into the C source for WBStarter to find out the details.
  100.  
  101.  
  102.   IV. Compilation
  103.  
  104. This program was compiled with DICE, Matt Dillon's superb C compiler. Just
  105. say "DMake" and it will produce the binary.
  106.  
  107.    V. History
  108.  
  109. 1.2 (21.09.1992)
  110.     - corrected version strings
  111.  
  112. 1.1 (13.09.1992)
  113.     - Fixes weird return bug in WBStart
  114.     - Fixes "Insert volume PROGDIR:..." bug
  115.  
  116. 1.0 (24.11.1991)
  117.     - Initial release
  118.  
  119.     Stefan Becker
  120.